docs: Add example of relations with lists of references

diff --git a/docs/reference/gtk/section-accessibility.md b/docs/reference/gtk/section-accessibility.md
index b86aac419be41de1bc3e6c763e7a8ad4f4c6982e..b8145e0ad358aa242444b7967720c0b68dc1f1d9 100644 (file)
--- a/docs/reference/gtk/section-accessibility.md
+++ b/docs/reference/gtk/section-accessibility.md
@@ -165,13 +165,13 @@ Each relation name is part of the #GtkAccessibleRelation enumeration.
 | %GTK_ACCESSIBLE_RELATION_COL_INDEX | “aria-colindex” | integer |
 | %GTK_ACCESSIBLE_RELATION_COL_INDEX_TEXT | “aria-colindextext” | translatable string |
 | %GTK_ACCESSIBLE_RELATION_COL_SPAN | “aria-colspan” | integer |
-| %GTK_ACCESSIBLE_RELATION_CONTROLS | “aria-controls” | a #GList of #GtkAccessible |
-| %GTK_ACCESSIBLE_RELATION_DESCRIBED_BY | “aria-describedby” | a #GList of #GtkAccessible |
-| %GTK_ACCESSIBLE_RELATION_DETAILS | “aria-details” | a #GList of #GtkAccessible |
+| %GTK_ACCESSIBLE_RELATION_CONTROLS | “aria-controls” | a list of #GtkAccessible |
+| %GTK_ACCESSIBLE_RELATION_DESCRIBED_BY | “aria-describedby” | a list of #GtkAccessible |
+| %GTK_ACCESSIBLE_RELATION_DETAILS | “aria-details” | a list of #GtkAccessible |
 | %GTK_ACCESSIBLE_RELATION_ERROR_MESSAGE | “aria-errormessage” | #GtkAccessible |
-| %GTK_ACCESSIBLE_RELATION_FLOW_TO | “aria-flowto” | a #GList of #GtkAccessible |
-| %GTK_ACCESSIBLE_RELATION_LABELLED_BY | “aria-labelledby” | a #GList of #GtkAccessible |
-| %GTK_ACCESSIBLE_RELATION_OWNS | “aria-owns” | a #GList of #GtkAccessible |
+| %GTK_ACCESSIBLE_RELATION_FLOW_TO | “aria-flowto” | a list of #GtkAccessible |
+| %GTK_ACCESSIBLE_RELATION_LABELLED_BY | “aria-labelledby” | a list of #GtkAccessible |
+| %GTK_ACCESSIBLE_RELATION_OWNS | “aria-owns” | a list of #GtkAccessible |
 | %GTK_ACCESSIBLE_RELATION_POS_IN_SET | “aria-posinset” | integer |
 | %GTK_ACCESSIBLE_RELATION_ROW_COUNT | “aria-rowcount” | integer |
 | %GTK_ACCESSIBLE_RELATION_ROW_INDEX | “aria-rowindex” | integer |
@@ -179,6 +179,10 @@ Each relation name is part of the #GtkAccessibleRelation enumeration.
 | %GTK_ACCESSIBLE_RELATION_ROW_SPAN | “aria-rowspan” | integer |
 | %GTK_ACCESSIBLE_RELATION_SET_SIZE | “aria-setsize” | integer |
 
+*Note*: When using gtk_accessible_update_relation() with a relation that
+requires a list of #GtkAccessible instances, you should pass every
+accessible object separately, followed by %NULL. 
+
 ## Application development rules
 
 Even if standard UI controls provided by GTK have accessibility information

diff --git a/gtk/gtkaccessible.c b/gtk/gtkaccessible.c
index 39c31d5b1ee08b3992ae819254d38084461fc34d..13c4cb35edf4f5521ee4c86c9a3f6791c4b03194 100644 (file)
--- a/gtk/gtkaccessible.c
+++ b/gtk/gtkaccessible.c
@@ -411,6 +411,18 @@ gtk_accessible_reset_property (GtkAccessible         *self,
  *
  * This function should be called by #GtkWidget types whenever an accessible
  * relation change must be communicated to assistive technologies.
+ *
+ * If the #GtkAccessibleRelation requires a list of references, you should
+ * pass each reference individually, followed by %NULL, e.g.
+ *
+ * |[<!-- language="C" -->
+ *   gtk_accessible_update_relation (accessible,
+ *                                   GTK_ACCESSIBLE_RELATION_CONTROLS,
+ *                                     ref1, NULL,
+ *                                   GTK_ACCESSIBLE_LABELLED_BY,
+ *                                     ref1, ref2, ref3, NULL,
+ *                                   -1);
+ * ]|
  */
 void
 gtk_accessible_update_relation (GtkAccessible         *self,